Agent 上下文工程
一个跑了四十轮的 Agent，上下文从 3K 涨到 180K。窗口还没满，但它开始重复调已经调过的工具、忘记第五轮定下的约束、对着一份自己十轮前读过的文件再读一遍。
这不是模型退化，是上下文里能用的东西被不能用的东西挤掉了。上下文工程要解决的就是这件事：在每一轮里决定往那个有限的窗口里放什么、不放什么、放在哪个位置。
先约定几个词，本专题全程使用：
| 词 | 意思 |
|---|---|
| 上下文工程 | 在推理时策划并维护那组进入模型的 token。区别于提示工程 —— 后者只管怎么把一次指令写好，前者管的是每一轮该带什么进来 |
| 注意力预算 | 一个类比：模型对上下文的有效利用能力是有限的，越长越摊薄。它不是硬上限，而是一条持续下滑的曲线 |
| 上下文腐烂（context rot） | 输入变长导致模型表现变差的现象，即使任务本身没变难。02 篇给实测形态 |
| 压缩（compaction） | 把旧内容总结成一段摘要，替换掉原文。有损，但保留语义 |
| 裁剪（context editing） | 直接删掉特定内容（比如老的工具结果），不做总结。更省，但删掉就是删掉了 |
| 卸载（offload） | 把内容挪到上下文之外（文件、子 Agent、外部存储），需要时再取回一小部分 |
| 前缀缓存 | 模型服务对请求前缀的缓存。前缀有一个字节变化，后面全部要重算 |
| 延迟加载（defer_loading） | 工具定义先不进上下文，等模型搜索到再加载。05 篇的主要手段 |
一、三组问题
二、七篇正文
| # | 标题 | 覆盖内容 |
|---|---|---|
| 01 | 窗口里装了什么 | 五个 token 去向与各自的增长曲线、预算怎么分配、有效利用率这个指标怎么算、上下文工程与提示工程的分界 |
| 02 | 上下文腐烂 | 18 个模型的实测形态、三个反直觉结论（打乱语料反而更好等）、位置效应、注意力预算的机制解释 |
| 03 | 压缩与裁剪 | 服务端压 缩与上下文裁剪的分工、全部配置项与默认值、两个静默失效（摘要块丢失、工具打断摘要）、成本口径陷阱 |
| 04 | 卸载到外部 | 结构化笔记、子 Agent 隔离上下文、即时检索三条路线的取舍，以及各自把什么问题推到了哪里 |
| 05 | 工具与检索结果的占用 | 工具定义膨胀的实测量级、延迟加载与工具搜索、30 到 50 个工具的选择准确率拐点、检索结果分页 |
| 06 | 前缀缓存与排布 | 渲染顺序与断点放置、六类静默失效的审计清单、裁剪与压缩各自怎么影响缓存、怎么验证 |
| 07 | 观测与落地 | 该看哪五个指标、怎么给上下文构成打点、常见反模式清单、四步落地顺序 |
只读两篇的话：05 篇（工具与检索结果）和 06 篇（前缀缓存）。前者是省得最多的一处，后者决定你省下来的 token 会不会被缓存失效吃回去。
三、三个需要先知道的前提
3.1 "上下文腐烂"有实测支撑，不是修辞
Chroma 2025 年 7 月的技术报告在 18 个模型（含 GPT-4.1、Claude 4、Gemini 2.5、Qwen3 系列）上做了控制变量实验，结论是模型并不均匀地使用上下文：同一个任务，只把输入拉长，表现就会下降。
更早的《Lost in the Middle》（arXiv 2307.03172）给出了位置维度的版本：相关信息放在开头或结尾时表现最好，放在中间显著变差 —— 即使是专门做长上下文的模型也一样。
细节和三个反直觉结论在 02 篇。
3.2 压缩、裁剪、卸载是三件事，经常被当成一件
| 手段 | 做什么 | 内容还在不在 | API 层的对应物 |
|---|---|---|---|
| 压缩 | 把旧内容总结成一段摘要 | 语义在，原文没了 | compact_20260112，beta compact-2026-01-12 |
| 裁剪 | 直接删掉特定块（老工具结果、思考块） | 不在了 | clear_tool_uses_20250919 / clear_thinking_20251015，beta context-management-2025-06-27 |
| 卸载 | 挪到窗口外，用时再取一小部分 | 完整在外部 | 记忆工具、子 Agent、你自己的文件系统 |
三者不是替代关系，代价也完全不同 —— 压缩要多花一次模型调用，裁剪不花钱但会破缓存，卸载不花钱但要多花模型轮次。03 篇和 04 篇分别展开。
3.3 每一次上下文改动都是一次缓存事件
这是这一层最容易被忽略、也最直接影响账单的一条。缓存读取的价格约是常规输入的十分之一，缓存写入约是 1.25 倍 —— 把一段本来能命中缓存的前缀改掉，省下的 token 常常不如多付的缓存写入贵。
官方文档在裁剪那一节专门给了一个参数来应对：clear_at_least 指定"至少要清掉这么多 token 才值得执行这次清理"。这个参数的存在本身就说明了问题的量级。06 篇是这条前提的展开。
四、本专题拆解的对象
数据核对于 2026-08-25，API 参数与默认值以官方文档为准。
4.1 三类 API 能力
| 能力 | 标识 | Beta 头 | 关键默认值 |
|---|---|---|---|
| 服务端压缩 | compact_20260112 | compact-2026-01-12 | 触发阈值 150,000 输入 token，最低可设 50,000 |
| 工具结果裁剪 | clear_tool_uses_20250919 | context-management-2025-06-27 | 触发 100,000 输入 token，保留最近 3 次工具调用 |
| 思考块裁剪 | clear_thinking_20251015 | 同上 | 默认行为按模型档次不同，跨档运行时必须显式设 keep |
| 工具搜索（正则） | tool_search_tool_regex_20251119 | 无 | 每次搜索默认返回 5 个工具，最多 10,000 个延迟加载工具 |
| 工具搜索（BM25） | tool_search_tool_bm25_20251119 | 无 | 同上 |
逐条拆在 03 和 05 篇。注意压缩与裁剪是两套独立的 beta，混用一个 beta 头会被拒。
4.2 两份实证材料
| 材料 | 时间 | 在本专题里的角色 |
|---|---|---|
| Chroma《Context Rot》技术报告 | 2025-07 | 02 篇的主要依据。18 个模型、多组控制变量实验 |
| Lost in the Middle（arXiv 2307.03172） | 2023-07（2023-11 修订） | 位置效应的出处，06 篇排布建议的依据之一 |
4.3 一套官方方法论
Anthropic 的《Effective context engineering for AI agents》给出了这一层的框架：把上下文当成有限资源来策划，长周期任务用压缩、结构化笔记、子 Agent 三种手段。本专题 03 到 04 篇沿用这个划分，但把每种手段的代价补齐 —— 原文更多讲怎么用，较少讲什么时候不该用。
五、与其他专题的关系
- Agent 记忆：记忆负责"跨会话存什么"，本专题负责"这一轮往窗口里放什么"。记忆读回来之后的注入位置与预算分配，是本专题 06 篇的内容
- Agent 编排范式：子 Agent 隔离上下文（04 篇）同时也是一种编排选择，那个专题讲它的调度语义，本篇讲它的上下文账
- Multi-Agent 产品源码分析：那个专题拆的几个产品里，上下文管理策略是最主要的差异点之一
- Agent 可观测性：07 篇要打的那几个点，落在那个专题定义的 span 属性上
同板块的其他专题：Agent 框架横向对比 | Agent 编排范式 | Multi-Agent 产品源码分析